Contents
HelpMake v.1.01

This software is declared FREEWARE.

Copyright © Quintin Willison, 1994.

A Moose Production.

This documentation contains information on the use of the HelpMake program.

Please select from one of the following:

  Overview

  Topic

  Settings

  Generating your Help File

  Menu Options

  Topic Edit Window

  Limitations

  Revision History

  Other Moose Productions

  Contacting the Author


Overview of HelpMake
Overview

The in thing...

Almost every windows application you come across now a days, from the very small to the gigantic and huge, will be accompanied by some Help Documentation to be run by the Windows Help program. The quality of this documentation varies, but it's normally there - most often placed on the Help menu. When you ask for help on an application it will run the WIndows Help program passing it the filename of it's particular help file. This help file will have an extension of .HLP and will most likely be found either in the directory of the application, or dumped in your Windows directory.

Microsoft DOS Help Compiler

The exact format of the .HLP file seems to be something that not many people know, and so the actual creation of this file is left to be the job of Microsoft's own Help Compiler program. The Microsoft Help Compiler is a DOS program.

The Microsoft Help Compiler needs two files to be created as the source files to build the .HLP file from. One of these files is a simple text file, which specifies information as to what the help window should be titled, whether the .HLP file should be compressed, etc.. This file has the extension .HPJ and is normally quite small. The other file will have the extension .RTF and is in the Microsoft Rich Text file format. This format is quite complicated to write (almost impossible by hand with a text editor) and contains the actual content to be put into the .HLP file.

Writing RTF

So far, I have explained that to create a .HLP file:

filename.HPJ + filename.RTF ----> Help Compiler Prog ----> filename.HLP

This is quite a simple concept, but what I have not yet explained is how the .RTF file is created.

At the moment, as far as I'm aware, unless you want to spend hundreds of pounds on a dedicated Help Development system, you need to spend not quite hundreds of pounds on a copy of Microsoft Word or similar to be able to generate .RTF files, as the format of these files is too complex to attempt to write by hand.

You also need to spend time getting to know the format of .HPJ files so that you can write them for your particular help projects.

These two facts, the cost and complication of creating .RTF files, and the concepts involved in creating the .HPJ file have lead a number of software developers to try and create their own (crappy) help systems, and to frighten off the casual home user who might of just wanted to create a quick help file - maybe to remember some things, quick reference, or even publish a book.

HelpMake

HelpMake get's around these problems by taking the legwork out of creating Windows Help files. HelpMake does the following:

  -  provides you with a comfortable development environment in which to write your Help file source text

  -  automatically generates the .RTF file

  -  automatically generates the .HPJ file

  -  runs the Microsoft DOS Help Compiler for you

HelpMake saves your source text for your help file in HelpMake's own .HMK file format. The .HMK file format also stores information on the title of your help file, and it's font styles etc..

HelpMake files are a nice compact file format, and allow you to distribute your Help file source to other people who have the HelpMake program if you want.

Related Topics

Topic

Settings

Generating your Help File


Moose Productions
Other Moose Productions

SOUND FX v.2.00 (20 April 1994)

(version 3.00 to be released by Christmas 1994)

Sound FX allows you to have full control over your PC Sound card and CD ROM Drive. The aim from the start was to build up a program suite that allows the user to gain information on the Sound sources on their PC, to play those sounds, and to cue those sounds into ordered sequences that could then be played back at leisure. Sound FX is decalared as FREEWARE software.

The following sound capabilities of your PC are currently supported:

  - Digitised Sound Samples (WAV files)

  - MIDI Sequencer Music (MID files)

  - CD Audio

Version 3.00 of Sound FX promises to include among other extras a full CD Tracks database, a Cutting Room window, a Special FX window, and a vastly improved interface feel.

POSTIT v.1.00 (14 August 1994)

As it's name implies, Postit allows you to put sticky Postit note style messages on users machines when they either want to run a particular program, or when they click on an icon you create for them. As well as displaying messages, Postit will also accompany the messages with multimedia events and can act as a "Do you really want to do this?" warning before someone runs a program. Postit is declared as FREEWARE software.

Contact the Author for more information.


Contacting the Author

The author of Moose Productions software can be contacted by letter at:

    Quintin Willison

    Moose Productions

    The Old Rectory

    Norfolk

    NR16 1RW

    UK

or by Electronic Mail at:

    Q.D.Willison@herts.ac.uk

I will be pleased to hear from anybody who is using the software, not only in order to get an idea of how widely it is getting used, but also to get suggestions and bug reports. I was tempted to release this under the somewhat dubious 'Cardware' banner, but I am against putting ANY sort of pressure on users to waste time contacting me if they like and use the software.

I am currently at university doing a Computer Science course, and so the E-mail address above should be valid until about mid 1997, and will only be likely to get a response within normal term times.


Topic

A topic in a help file is a body of text which is displayed to the user in one lump that they can scroll through. This section you are reading on Topic's is written as one topic in my help file!

Contents

The topic that the help file starts up on as the Contents page must always exist in a HelpMake project and must be called CONTENTS although it's title text and index entry text may change.

Formatting

The format of a HelpMake topic consists the Topic Title first, which is always displayed in your Topic Header Text Font, followed by your help files main text for that topic in your Topic Body Text Font.

Within the topic body text can be paragraphs which have been assigned specific formatting attributes. This is done through the use of Special Codes inserted into your source text. These codes must be at the beginning of a paragraph, and take the form of two vertical pipe symbols with a character inbetween them (e.g. |B| specifies bold paragraph). A number of these Special Codes can be used together, although they must all be placed at the beginning of the paragraph or else they will be interpreted as body text.

Hyper-links

In order for the user of your help documentation to be able to get to read what they want to quickly you insert hyper-links into the body text. Hyper-links are highlighted underlined words (normally in green) which can be clicked on to go to a specific topic.

Related Topics

Settings

Topic Edit Window


Settings

The presentation of your entire help file can be very drastically changed quickly by the use of the Settings dialog.

Click on Settings under the project menu.

You can change the following:

Help Window Title

This is the text that Windows Help should display in it's title bar when running your help file.

Compress Help File

Check this box if you want the Microsoft Help Compiler to compress the .HLP file it creates. This option is best left on, although the Help file 'might' display a bit quicker if you leave it off (but it will take up more disk space).

Font Styles

This allows you to format the appearance of text in your help file.

Related Topics

Topic


Fonts

The font style settings for the current project can be found in the Project Settings window. Click on Settings under the Project menu.

The font type (sans serif, serif or courier) can be selected, as well as font size and styling (bold, italic).

The Element list box in the Font Styles are enables you to select which font style you wish to define. The following font styles can be defined:

Topic Header Text

This is the style that the title line of a topic is displayed in. It should usually be designed to be bigger and bolder that the body text for a topic.

Topic Body Text

This is the font style that the main text of the topic appears in.

Topic Body Hyperlink Text

This is the style that hyperlinks appear in. Only the font type can be changed here, not size or appearance, as they will be taken from the body text settings.


HelpMake Limitations

HelpMake has the following limitations:

  -  maximum size of 32Kbytes worth of text possible for each topic.

  -  maximum number of topics for each project is 256.

  -  maximum size of topic Index entry texts is 32 characters.

  -  maximum size of topic Title texts is 64 characters.

  -  maximum number of topics editable at one time is 8.

  -  only one HelpMake project can be edited in any one HelpMake program instance, although the program can be loaded several times.

  -  The tilde character is reserved for hyperlinks and so CANNOT be used anywhere in your text.

  -  There is no support for dynamic foreign text file inclusion upon creation of the RTF file. This would be useful if you had a standard topic text that you always have in every help file you write.

The following features of windows help are not currently supported. They may be able to be implemented in later versions of HelpMake.

  -  bitmap images.

  -  multi-level indexes.

  -  full text formatting (within one paragraph)

  -  setting of tab stops, and the use of them

  -  anchored header and footer sections

  -  capability to call windows DLLs

Some of these features really need HelpMake to go WYSIWYG to enable them to be implemented properly.

Contact the Author if you have any suggestions as to ways in which HelpMake could be improved in any way.


Special Codes

Special codes can be inserted into your text automatically for you by HelpMake from a pick list, or typed in manually. They consist of a character surrounded by two vertical pipe symbols. To insert a code, place your cursor at the beginning of a paragraph, and then either use the key shortcut CTRL+C or select Insert Special Code from the Topic menu.

The following special codes may be inserted at the beginning of a paragraph, and in most cases apply to any text in that paragraph, and only that paragraph.

Bold

Bold text font style

Box Paragraph

The text in the paragraph should be surrounded by a box:

This is an example of a paragraph which has had a Box Paragraph code inserted at it's start. It appears in a box as you can see...

very nice, yes, very nice! This text is in the next paragraph, and so is not included in the box.

Dotted Underline

Broken dotted underline text.

Double Underline

Double Underline text.

Horizontal Split

This does not specify formatting for the following text. It just inserts a line right across the page. For use to visually split paragraphs up. Typically inserted on it's own on a line.

Indent level <n>

Set's left margin indentation to specified level <n> which can be from 1 to 9.

This is an example of level 1 indentation.

This is an example of level 9 indentation.

This is an example of level 5 indentation, if you have not got the help window very wide you will notice that the text wraps around over the edge of the line properly at this indentation distance as well, meaning that you never need to put in a grotty hard return when you don't need to!!

Italic

Italic text font style.

Numbered Indented Paragraph

Set's the page indentation so that a number list can be displayed:

1) This is an example of a numbered indented paragraph. The numbered indented paragraph code was inserted before the text 1) at the beginning of the paragraph.

2) This is another numbered indented paragraph. It has to have it's own numbered indented paragraph code inserted at the start.

* This paragraph is an example of one formatted with numbered indented paragraph code at the beginning but showing that it does not have to be a number at the beginning of the paragraph. It is just that the indentations are optimised to display numbered paragraphs visibly.

Underline

Single underline text.

Word Underline

Single underline words only.


Generating Your Help File

Once you have written all or part of your HelpMake project you will need to get it generated into a Windows .HLP file so that you can test it.

Build All

Click on Build All under the Project menu.

This firstly creates the RTF and HLP files and then runs the Microsoft Help Compiler to generate your final help file.

Run HLP File

Click on Run HLP File under the Project menu.


Create RTF/HPJ

This does the following:

1) Checks through your HelpMake project to make sure that you have not got any incorrect hyperlinks.

2) Creates the RTF file from which the Microsoft Help Compiler can get the text of your project.

3) Creates the HPJ file from which the Microsoft Help Compiler can get basic information about your project.

Create RTF/HPJ is executed as the first stage in a Build All operation, but can be run on it's own by clicking on Create RTF/HPJ under the Project menu.


Generate HLP

This runs the Microsoft Help Compiler giving it the current project's file name to compile.

This option requires that you have the following two files in your WINDOWS directory:

  HC31.EXE

  HC31.PIF

HC31.EXE is the Microsoft Help Compiler for DOS, and HC31.PIF is a settings file for windows to enable it to run HC31.EXE windowed and without problems. You can edit HC31.PIF according to your own tastes (use the Windows PIF Editor) although it is advised to make a backup copy before hand.

Generate HLP is executed as the second stage in a Build All operation, but can be run on it's own by clicking on Generate HLP under the Project menu.


Run HLP File

This shows you a dialog asking you how you would like to run the help file.

You can either go to the contents page, or specify a particular topic's map ID in the number entry box.


Create New Topic

To create a new topic in your Help file, either click on Create New under the Topic menu, or click on the fourth button in the strip next to the topic code in a topic window. This button represents a blank sheet and will create a new topic for editing in that window. Using Create New under the Topic menu will open a new window for editing the new topic in.

Topic Code

The code you enter for the topic must not be in use by any other topic, and can only include alphabet characters or the underscore symbol. For convenience, the dialog automatically puts in an underscore for you if you press the space bar. Topic codes must be in capital letters.

Related Topics

Topic Edit Window


Topic Edit Window

This is where you do all the writing of your Help file.

Topic

This box displays the topic code for the topic currently being edited in this window.

There are four buttons to the right of it. From left to right:

1) Click on the drop down list button to bring up a list of topics in order to edit another topic in this window.

2) Click on the left pointing arrow to browse through topics.

3) Click on the right pointing arrow to browse through topics in the other direction.

4) Click on the blank sheet button to create a new topic.

Map ID

Check the box to tell HelpMake to inform the Microsoft Help Compiler (in the HPJ file's [Map] section) a unique map number for this topic. HelpMake always assigns a map ID number to each topic when it is created, but it does not enable them until you explicitly ask it to.

Map IDs are used by windows applications to give context sensitive help to the user, and are the easiest link through which an application can inform the Help program which topic it wants displayed.

Title

This is the text that you wish to appear at the top of the page for this topic.

Index

Check the box if you wish for this topic to be accessible from a user search of the help file in the Help program. If checked, HelpMake will create an index entry with the title text you specify in the text box to the right of the Index check box.

Body Text

The large white space in the rest of the window is where you enter the body text for this topic.

Save Me....

HelpMake automatically manages the saving of topic text and settings to memory every time you change to a new topic in a topic window.

However, you still need to Save your HelpMake project to disk from time to time!

Related Topics

Settings


Menu Options

Here follows descriptions of the use of all the options available under the HelpMake menus:

File menu

New

Create a new HelpMake project. You will be prompted to save the current project if it has been modified since you last saved it.

Open...

Load a previously created HelpMake project for editing.

Save

Save the HelpMake project under it's current filename. If it's an as yet un-saved HelpMake project then prompt for a filename to save it under.

Save as...

Prompt for a filename to save the HelpMake project under even if it has already been saved.

Exit

Bye Bye!!

Project menu

Settings

Opens up the global settings window.

Create RTF/HPJ

Creates the RTF and HPJ source files needed by the Microsoft Help Compiler.

Generate HLP

Runs the Microsoft Help Compiler.

Build All

Firstly creates the RTF/HPJ files and then runs the Microsoft Help Compiler.

Run HLP File

Use for testing your Help project. Runs the Windows Help program.

Topic menu

Create New

Create a new topic, opening a new window to edit it in.

View

Open up a new edit window to edit an existing topic in. If the topic is currently displayed in any edit window, then that edit window will be shown (a topic cannot be edited in more than one window at once).

Rename

Change the topic code of the topic in the currently selected topic edit window.

Delete

Delete the topic in the currently selected topic edit window from the project.

Insert Hyper-link

Insert a hyper-link to another topic into the currently selected topic edit window at the current cursor position.

Insert Special Code

Insert a special code into the currently selected topic edit window at the current cursor position. Codes are only valid if placed at the VERY beginning of a paragraph.

Window menu

Self Explanatory.

Help menu

Self Explanatory.


Hyper-links

There are two types of Hyper-link supported by HelpMake. Standard and Popup. Standard simply loads the topic over the current one in the same window. Popup displays a small un-bordered window on top of this one to display the other topic. The user then has to click on the small window to get back to the topic the hyper-link they clicked on was in. This is typically used for quick glossary or lookup help topics.

Hyper-links in your source text take the form of a tilde followed by some text to be displayed to the user followed by another tilde which is followed by the code of the topic to go to followed by a final third tilde.

This means that the tilde character is a reserved character in HelpMake and CANNOT be represented in your help body text at all.

To insert a hyper-link automatically (rather than having to remember the above sequence of characters) just use the keyboard shortcut CTRL+L or select Insert Hyper-link from the Topic menu. You will then have to select the topic you wish the link to jump to. Then you have to enter what the text the user clicks on should be, as well as checking a box if you wish the hyperlink to put the topic up in a popup window.


Revision History

v.1.00 - 18 October 1994

Original version.

Released to ftp site ftp.sunet.se.

v.1.01 - 28 October 1994

Altered the path search routine so that it looks for HC31.PIF in Windows, System, Working Directory and the Path.

Released on PChome cover CD, as well as miscellaneous ftp sites.